<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta content='width=device-width, initial-scale=1.0' name='viewport'>
    <meta content='' name='description'>
    <meta content='Nils Nordman' name='author'>
    <link href='/images/howl.png' rel='shortcut icon'>
    <title>Howl :: howl.io.Process</title>
    <link href="/stylesheets/bootstrap.min.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/syntax.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/howl.css" media="screen" rel="stylesheet" type="text/css" />
    <link href='//fonts.googleapis.com/css?family=Josefin+Slab' rel='stylesheet' type='text/css'>
    <link href='//fonts.googleapis.com/css?family=Open+Sans+Condensed:700' rel='stylesheet' type='text/css'>
  </head>
  <body class='doc doc_api doc_api_io doc_api_io_process'>
    <div class='container'>
      <div class='masthead'>
        <ul class='nav nav-pills'>
          <li>
            <a href='/'>
              <span class='glyphicon glyphicon-home'></span>
              Home
            </a>
          </li>
          <li>
            <a href='/doc/'>
              <span class='glyphicon glyphicon-book'></span>
              Documentation
            </a>
          </li>
          <li>
            <a href='/blog/'>
              <span class='glyphicon glyphicon-bullhorn'></span>
              Blog
            </a>
          </li>
          <li>
            <a href='/contact.html'>
              <span class='glyphicon glyphicon-inbox'></span>
              Contact
            </a>
          </li>
        </ul>
      </div>
      <ol class="breadcrumb"><li><a href="/">Home</a></li><li><a href='../../'>Howl 0.3 Documentation</a></li><li>Api</li><li>Io</li><li>howl.io.Process</li></ol>
      <h1 id="howl.io.process">howl.io.Process</h1>    <div class="toc">
      <div class="toc-title">
        <span>howl.io.Process</span>
      </div>
      <div class="toc-entries">
<div class="toc-group">
<a href="#overview" class="toc-group-header overview">Overview</a>
</div>
<div class="toc-group">
<a href="#class-properties" class="toc-group-header class_properties">Class Properties</a>
<li class=""><a href="#running">running</a></li>
</div>
<div class="toc-group">
<a href="#properties" class="toc-group-header properties">Properties</a>
<li class=""><a href="#argv">argv</a></li>
<li class=""><a href="#command_line">command_line</a></li>
<li class=""><a href="#exited">exited</a></li>
<li class=""><a href="#exited_normally">exited_normally</a></li>
<li class=""><a href="#exit_status">exit_status</a></li>
<li class=""><a href="#pid">pid</a></li>
<li class=""><a href="#signal">signal</a></li>
<li class=""><a href="#signalled">signalled</a></li>
<li class=""><a href="#signal_name">signal_name</a></li>
<li class=""><a href="#exit_status_string">exit_status_string</a></li>
<li class=""><a href="#stderr">stderr</a></li>
<li class=""><a href="#stdin">stdin</a></li>
<li class=""><a href="#stdout">stdout</a></li>
<li class=""><a href="#successful">successful</a></li>
<li class=""><a href="#working_directory">working_directory</a></li>
</div>
<div class="toc-group">
<a href="#functions" class="toc-group-header functions">Functions</a>
<li class=""><a href="#process">Process</a></li>
<li class=""><a href="#execute">execute</a></li>
</div>
<div class="toc-group">
<a href="#methods" class="toc-group-header methods">Methods</a>
<li class=""><a href="#pump">pump </a></li>
<li class=""><a href="#send_signal">send_signal </a></li>
<li class=""><a href="#wait">wait </a></li>
</div>
</div>
</div>
&#x000A;&#x000A;<h2 id="overview">Overview</h2>&#x000A;&#x000A;<p>The Lua runtime itself only provides rudimentary support for running processes,&#x000A;in the form of&#x000A;<a href="http://www.lua.org/manual/5.2/manual.html#pdf-os.execute">os.execute</a> and&#x000A;<a href="http://www.lua.org/manual/5.2/manual.html#pdf-io.popen">io.popen</a>. Apart from&#x000A;not providing any way of more advanced interaction with the process, such as&#x000A;sending signals, the above both suffer from the flaw of blocking program&#x000A;execution. In the context of an interactive application, such as Howl, this is&#x000A;unacceptable is it means the application will be unresponsive while waiting for&#x000A;command termination or output. The howl.io.Process module provides a way of&#x000A;launching and interacting with external processses that, while still providing&#x000A;the appearance and ease of use of a synchronous API, is fully asynchronous and&#x000A;ensures Howl remains responsive.</p>&#x000A;&#x000A;<p><em>See also</em>:</p>&#x000A;&#x000A;<ul>&#x000A;<li>The <a href="../../spec/io/process_spec.html">spec</a> for Process</li>&#x000A;</ul>&#x000A;&#x000A;<h2 id="class-properties">Class Properties</h2>&#x000A;&#x000A;<h3 id="running">running</h3>&#x000A;&#x000A;<p>A table containing all currently running processes, keyed by the process pid.</p>&#x000A;&#x000A;<h2 id="properties">Properties</h2>&#x000A;&#x000A;<h3 id="argv">argv</h3>&#x000A;&#x000A;<p>The argument list that was used to launch the process.</p>&#x000A;&#x000A;<h3 id="command_line">command_line</h3>&#x000A;&#x000A;<p>A string representation of the command run. If the process was created using a&#x000A;string command (<code>cmd</code> was specified as a string), this will be equal to the&#x000A;passed in command. If the process was created using a argument table, this will&#x000A;be a space separated string with any arguments containing blanks being quoted&#x000A;using single quotes.</p>&#x000A;&#x000A;<h3 id="exited">exited</h3>&#x000A;&#x000A;<p>True if the process has terminated, normally or not, and false otherwise.</p>&#x000A;&#x000A;<h3 id="exited_normally">exited_normally</h3>&#x000A;&#x000A;<p>True if the process terminated normally, i.e. due to an explicit exit or a&#x000A;return from <code>main</code>, and false otherwise. Only available once the process has&#x000A;exited (<a href="#exited">exited</a> is true).</p>&#x000A;&#x000A;<h3 id="exit_status">exit_status</h3>&#x000A;&#x000A;<p>The exit status of the process. Only available if the process has exited&#x000A;normally (<a href="#exited_normally">exited_normally</a> is true).</p>&#x000A;&#x000A;<h3 id="pid">pid</h3>&#x000A;&#x000A;<p>The process id of the process.</p>&#x000A;&#x000A;<h3 id="signal">signal</h3>&#x000A;&#x000A;<p>Holds the signal that caused the process to terminate. Only available if the&#x000A;process was indeed terminated due to a signal (<a href="#signalled">signalled</a> is true).</p>&#x000A;&#x000A;<h3 id="signalled">signalled</h3>&#x000A;&#x000A;<p>True if the process was terminated as the result of a signal. Only available&#x000A;once the process has exited (<a href="#exited">exited</a> is true).</p>&#x000A;&#x000A;<h3 id="signal_name">signal_name</h3>&#x000A;&#x000A;<p>A string representation of the signal that caused the process to terminate. Only&#x000A;available if the process was indeed terminated due to a signal&#x000A;(<a href="#signalled">signalled</a> is true).</p>&#x000A;&#x000A;<h3 id="exit_status_string">exit_status_string</h3>&#x000A;&#x000A;<p>A string containing a human readable representation of the process exit status.&#x000A;Only available once the process has exited (<a href="#exited">exited</a> is true).</p>&#x000A;&#x000A;<h3 id="stderr">stderr</h3>&#x000A;&#x000A;<p>An <a href="input_stream.html">InputStream</a> instance that can be used for reading the process&#39; error&#x000A;output. The process must have been created with the <code>read_stderr</code> option for&#x000A;this field to be available.</p>&#x000A;&#x000A;<h3 id="stdin">stdin</h3>&#x000A;&#x000A;<p>An <a href="output_stream.html">OutputStream</a> instance that can be used for writing to the process&#39; input.&#x000A;The process must have been created with the <code>write_stdin</code> option for this field&#x000A;to be available.</p>&#x000A;&#x000A;<h3 id="stdout">stdout</h3>&#x000A;&#x000A;<p>An <a href="input_stream.html">InputStream</a> instance that can be used for reading the process&#39; standard&#x000A;out. The process must have been created with the <code>read_stdout</code> option for this&#x000A;field to be available.</p>&#x000A;&#x000A;<h3 id="successful">successful</h3>&#x000A;&#x000A;<p>True if the process exited normally, with an exit code of zero. Only available&#x000A;once the process has exited (<a href="#exited">exited</a> is true).</p>&#x000A;&#x000A;<h3 id="working_directory">working_directory</h3>&#x000A;&#x000A;<p>A <a href="file.html">File</a> instance for the process&#39; working directory.</p>&#x000A;&#x000A;<h2 id="functions">Functions</h2>&#x000A;&#x000A;<h3 id="process">Process<span class="arg-list">(options)</span></h3>&#x000A;&#x000A;<p>Launches a new process with the specified options, and returns a Process&#x000A;instance. <code>options</code>, a table, can contain the following fields:</p>&#x000A;&#x000A;<ul>&#x000A;<li><p><code>cmd</code>: <em>[required]</em> The command to run. This can be either a string, in which&#x000A;case it&rsquo;s executed using <code>/bin/sh</code> (or using the shell specified by <code>shell</code>), or&#x000A;a table comprising the full command line invocation.</p></li>&#x000A;<li><p><code>read_stdout</code>: <em>[optional]</em> When specified, a pipe will be opened for the&#x000A;process&#39; standard out, and the <a href="#stdout">stdout</a> field will be available for&#x000A;reading the process&#39; output.</p></li>&#x000A;<li><p><code>read_stderr</code>: <em>[optional]</em> When specified, a pipe will be opened for the&#x000A;process&#39; error out, and the <a href="#stderr">stderr</a> field will be available for&#x000A;reading the process&#39; error output.</p></li>&#x000A;<li><p><code>write_stdin</code>: <em>[optional]</em> When specified, a pipe will be opened for the&#x000A;process&#39; input, and the <a href="#stdin">stdin</a> field will be available for writing to&#x000A;the process&#39; input.</p></li>&#x000A;<li><p><code>working_directory</code>: <em>[optional]</em> The path to set as the process&#39; working&#x000A;directory.</p></li>&#x000A;<li><p><code>env</code>: <em>[optional]</em> A table of keys and values that will be used as the&#x000A;process&#39; environment.</p></li>&#x000A;<li><p><code>shell</code>: <em>[optional]</em> A string specifying the shell to use for executing the&#x000A;command. The specified shell will be invoked with the <code>-c</code> parameter, with the&#x000A;command parameters directly following. This parameter is only respected if <code>cmd</code>&#x000A;is a string.</p></li>&#x000A;</ul>&#x000A;&#x000A;<p>An error will be raised if the specified command could not be started. Otherwise&#x000A;a process object is returned for the started command.</p>&#x000A;&#x000A;<h3 id="execute">execute<span class="arg-list">(cmd, options = {})</span></h3>&#x000A;&#x000A;<p>Executes a process for <code>cmd</code> and returns the results in one go. <code>cmd</code> can be&#x000A;either a string, in which case it&rsquo;s executed using <code>/bin/sh</code>, or a table&#x000A;comprising the full command line invocation. <code>options</code>, a optional table of&#x000A;options, can contain the following optional fields:</p>&#x000A;&#x000A;<ul>&#x000A;<li><p><code>stdin</code>: When specified, the contents of this field will be written as the&#x000A;process&#39; input.</p></li>&#x000A;<li><p><code>working_directory</code>: The path to set as the process&#39; working directory.</p></li>&#x000A;<li><p><code>env</code>: A table of keys and values that will be used as the process&#39;&#x000A;environment.</p></li>&#x000A;<li><p><code>shell</code>: <em>[optional]</em> A string specifying the shell to use for executing the&#x000A;command. The specified shell will be invoked with the <code>-c</code> parameter, with the&#x000A;command parameters directly following. This parameter is only respected if <code>cmd</code>&#x000A;is a string.</p></li>&#x000A;</ul>&#x000A;&#x000A;<p>An error will be raised if the specified command could not be started, or if an&#x000A;IO error occurs. Otherwise the function returns three values: The standard&#x000A;output of the command as a string, the error output of the command as a string,&#x000A;and the process object representing the terminated process.</p>&#x000A;&#x000A;<p>Examples:</p>&#x000A;<pre class="highlight moonscript"><span class="n">howl</span><span class="p">.</span><span class="n">io</span><span class="p">.</span><span class="nc">Process</span><span class="p">.</span><span class="n">execute</span><span class="w"> </span><span class="s1">'echo "foo bar"'</span><span class="w">&#x000A;</span><span class="c1">-- =&gt;  "foo bar\n", "", &lt;Process&gt;</span><span class="w">&#x000A;&#x000A;</span><span class="n">howl</span><span class="p">.</span><span class="n">io</span><span class="p">.</span><span class="nc">Process</span><span class="p">.</span><span class="n">execute</span><span class="w"> </span><span class="p">{</span><span class="s1">'sh'</span><span class="p">,</span><span class="w"> </span><span class="s1">'-c'</span><span class="p">,</span><span class="w"> </span><span class="s1">'echo foo &gt;&amp;2'</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="c1">-- =&gt;  "", "foo\n", "", &lt;Process&gt;</span><span class="w">&#x000A;&#x000A;</span><span class="n">howl</span><span class="p">.</span><span class="n">io</span><span class="p">.</span><span class="nc">Process</span><span class="p">.</span><span class="n">execute</span><span class="w"> </span><span class="s1">'pwd'</span><span class="p">,</span><span class="w"> </span><span class="ss">working_directory:</span><span class="w"> </span><span class="s1">'/bin'</span><span class="w">&#x000A;</span><span class="c1">-- =&gt;  "/bin\n", "", "", &lt;Process&gt;</span><span class="w">&#x000A;&#x000A;</span><span class="n">howl</span><span class="p">.</span><span class="n">io</span><span class="p">.</span><span class="nc">Process</span><span class="p">.</span><span class="n">execute</span><span class="w"> </span><span class="s1">'env'</span><span class="p">,</span><span class="w"> </span><span class="ss">env:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="ss">foo:</span><span class="w"> </span><span class="s1">'bar'</span><span class="w"> </span><span class="p">}</span><span class="w">&#x000A;</span><span class="c1">-- =&gt;  "foo=bar\n", "", "", &lt;Process&gt;</span><span class="w">&#x000A;&#x000A;</span><span class="n">howl</span><span class="p">.</span><span class="n">io</span><span class="p">.</span><span class="nc">Process</span><span class="p">.</span><span class="n">execute</span><span class="w"> </span><span class="s1">'cat'</span><span class="p">,</span><span class="w"> </span><span class="ss">stdin:</span><span class="w"> </span><span class="s1">'give it back!'</span><span class="w">&#x000A;</span><span class="c1">-- =&gt;  "give it back!", "", "", &lt;Process&gt;</span><span class="w">&#x000A;</span></pre>&#x000A;<h2 id="methods">Methods</h2>&#x000A;&#x000A;<h3 id="pump">pump <span class="arg-list">(on_stdout, on_stderr)</span></h3>&#x000A;&#x000A;<p>&ldquo;Pumps&rdquo; the process for any output, invoking either the <code>on_stdout</code> handler for&#x000A;any process output, or the <code>on_stderr</code> handler for any error output. The method&#x000A;will return once the process has exited. The <code>on_stdout</code> and <code>on_stderr</code>&#x000A;handlers will be invoked as soon as any output from the respective stream is&#x000A;available from the process, receiving as their sole argument the output as a&#x000A;string. As the process output streams are closed the handlers will be invoked a&#x000A;final time with nil, signifying end-of-file.</p>&#x000A;&#x000A;<p>Any of the two handlers (<code>on_stdout</code> and <code>on_stderr</code>) can be omitted in case&#x000A;you&rsquo;re only interested in one of the two. Note that you need to create the&#x000A;process with the corresponding <code>read_*</code> flag - <code>read_stdout</code> if <code>on_stdout</code> is&#x000A;specified, and <code>read_stderr</code> if <code>on_stderr</code> is specified.</p>&#x000A;&#x000A;<h3 id="send_signal">send_signal <span class="arg-list">(signal)</span></h3>&#x000A;&#x000A;<p>Sends <code>signal</code> to the process. <code>signal</code> can be either a number or a string&#x000A;representation of the signal, such as <code>HUP</code>, <code>KILL</code>, etc.</p>&#x000A;&#x000A;<h3 id="wait">wait <span class="arg-list">()</span></h3>&#x000A;&#x000A;<p>Waits for the process to terminate.</p>
      <div class='footer text-muted'>
        <a href='/'>
          <img width="50" height="50" class="footer-logo" src="/images/howl.png" />
        </a>
        <div class='footer-follow'>
          <p>
            <a class='twitter-follow-button' data-lang='en' data-show-count='false' href='https://twitter.com/howleditor' rel='me'>
              Follow @howleditor
            </a>
          </p>
          <p>
            <a class='twitter-share-button' data-count='none' data-hashtags='howleditor' data-lang='en' data-text='The Howl Editor, a general purpose, light-weight customizable editor.' data-url='http://howl.io' href='https://twitter.com/share'>
              Tweet
            </a>
          </p>
        </div>
        <div class='footer-blurb'>
          <div>The Howl editor.</div>
          <div>
            Copyright 2012-2015
            <a class='alert-link' href='https://github.com/nilnor/howl/contributors'>
              The Howl Developers.
            </a>
          </div>
        </div>
      </div>
    </div>
    <script>
      <!-- / GA -->
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
      ga('create', 'UA-45283282-1', 'howl.io');
      ga('send', 'pageview');
      <!-- / Twitter -->
      !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];
      if(!d.getElementById(id)){js=d.createElement(s);js.id=id;
      js.src="//platform.twitter.com/widgets.js";
      fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
    </script>
  </body>
</html>
